home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / installed_progs / dev / fsystem-1.2 / fsystem.txt < prev    next >
Encoding:
Text File  |  1994-05-22  |  11.3 KB  |  434 lines
  1. (* $VER: FSystem 1.2 (24-Nov-93) Copyright © by Lars Düning *)
  2.  
  3. DEFINITION FSystem;
  4.  
  5. ---------------------------------------------------------------------------
  6.  File handling library module for Amiga-Oberon.
  7.  
  8.  Copyright © 1991-1993  Lars Düning  -  All rights reserved.
  9.  Permission granted for non-commercial use.
  10. ---------------------------------------------------------------------------
  11.  
  12. BUGS:
  13.   Doesn't use the OS-2.0 buffered files.
  14.   Doesn't know multi-assigns.
  15.  
  16. TYPE
  17.  
  18.   FilePtr * = POINTER TO File;
  19.  
  20.  
  21. CONST
  22.  
  23.   StdBufSize *= 1024;  Default buffer size
  24.   cEof        = 1CX;   End-Of-File character
  25.  
  26.  
  27. CONST: Open() access modes
  28.  
  29.   newFile * = Dos.newFile;    excl. access, erases existing file
  30.   oldFile * = Dos.oldFile;    shared access, file has to exist
  31.   update  * = Dos.readWrite;  excl. access, file may exist
  32.  
  33.  
  34. CONST: Open() operation modes
  35.  
  36.   writeOnly * = 0;
  37.   readOnly  * = 1;
  38.   readWrite * = 2;
  39.  
  40.  
  41. CONST: File.status, error codes in fact
  42.  
  43.   ok        * = 0;  no error occured
  44.   eof       * = 1;  end of file reached
  45.   readerr   * = 2;  unspecified read error, ask Dos
  46.   writeerr  * = 3;  unspecified write error, ask Dos
  47.   onlyread  * = 4;  tried to write a read-only file
  48.   onlywrite * = 5;  tried to read a write-only file
  49.   toofar    * = 6;  seeked beyond the file's limits
  50.   outofmem  * = 7;  ran out of memory
  51.   cantopen  * = 8;  couldn't open file
  52.   cantlock  * = 9;  couldn't lock file
  53.  
  54. TYPE: The File structure, source level compatible to FileSystem
  55.  
  56.   File * = RECORD
  57.     handle * : d.FileHandlePtr;
  58.     status * : INTEGER;
  59.     write  * : BOOLEAN;
  60.     read   * : BOOLEAN;
  61.     name   * : POINTER TO ARRAY OF CHAR;
  62.     string * : bt.DynString;
  63.   END;
  64.  
  65.   The file structure makes no statements about the 'true' current
  66.   fileposition as managed by DosS (except .read is TRUE and .buflen 0).
  67.   That means that prior to every file operation using Dos at least
  68.   one Dos.Seek(file.pos) should happen, better a call to EmptyBuf() to
  69.   flush the internal buffers.
  70.  
  71.  
  72. PROCEDURE Use * (VAR    file: File
  73.                 ;       name: ARRAY OF CHAR
  74.                 ;    accMode: INTEGER
  75.                 ;    opMode : INTEGER
  76.                 ;    bufsize: LONGINT
  77.                 ): BOOLEAN;
  78.  
  79.  
  80.   Open a file according to access and operation mode.
  81.  
  82.   Arguments:
  83.     file: the empty(!) File structure to fill in.
  84.     name: the name of the file to open (will be copied into file).
  85.     accMode: the access mode to use.
  86.     opMode : the operation mode to use.
  87.     bufSize: size of the buffer to allocate, must be at least 1.
  88.  
  89.   Result:
  90.     TRUE on success, else FALSE with file.status denoting the error.
  91.  
  92.   A bufsize of 1 will result in unbuffered io.
  93.  
  94.  
  95. PROCEDURE open * (VAR    file: File
  96.                  ;       name: ARRAY OF CHAR
  97.                  ;    accMode: INTEGER
  98.                  ): BOOLEAN;
  99.  
  100.  
  101.   Open a file for read/write with a default sized buffer.
  102.  
  103.   Arguments:
  104.     file: the empty(!) File structure to fill in.
  105.     name: the name of the file to open (will be copied into file).
  106.     accMode: the access mode to use.
  107.  
  108.   Result:
  109.     TRUE on success, else FALSE with file.status denoting the error.
  110.  
  111.   The allocated buffer will be of StdBufSize.
  112.   The file will be opened for reading and writing.
  113.  
  114.  
  115. PROCEDURE Open * (VAR  file: File
  116.                  ;     name: ARRAY OF CHAR
  117.                  ;    write: BOOLEAN
  118.                  ): BOOLEAN;
  119.  
  120.   Open a file for read or write with a default sized buffer.
  121.  
  122.   Arguments:
  123.     file: the empty(!) File structure to fill in.
  124.     name: the name of the file to open (will be copied into file).
  125.     write: TRUE if the file shall be written, FALSE if it shall be read.
  126.  
  127.   Result:
  128.     TRUE on success, else FALSE with file.status denoting the error.
  129.  
  130.   The allocated buffer will be of StdBufSize. The file will be opened
  131.   for either reading or writing.
  132.  
  133.   This is a compatibility function to FileSystem.
  134.  
  135.  
  136. PROCEDURE OpenReadWrite * (VAR file: File; name: ARRAY OF CHAR) : BOOLEAN;
  137.  
  138.   Open a file for read and write with a default sized buffer.
  139.  
  140.   Arguments:
  141.     file: the empty(!) File structure to fill in.
  142.     name: the name of the file to open (will be copied into file).
  143.  
  144.   Result:
  145.     TRUE on success, else FALSE with file.status denoting the error.
  146.  
  147.   The allocated buffer will be of StdBufSize. The file will be opened
  148.   for reading and writing.
  149.  
  150.   This is a compatibility function to FileSystem.
  151.  
  152.  
  153. PROCEDURE Flush    * (VAR file: File): BOOLEAN;
  154. PROCEDURE FlushBuf * (VAR file: File): BOOLEAN;
  155.  
  156.   Flush the buffers of a file.
  157.  
  158.   Arguments:
  159.     file: the file to flush.
  160.  
  161.   Result:
  162.     TRUE on success, else FALSE with file.status denoting the error.
  163.     file will be update appropriately.
  164.  
  165.   If the file has been changed, this call will flush the internal buffer
  166.   out to the disk file. To do this, the file.buflen bytes starting
  167.   from file.buffer[0] are written, then the old file.pos will be seeked.
  168.  
  169.  
  170. PROCEDURE close * (VAR file: File);
  171. PROCEDURE Close * (VAR file: File): BOOLEAN;
  172.  
  173.   Close the file.
  174.  
  175.   Arguments:
  176.     file: the file to close.
  177.  
  178.   Result:
  179.     TRUE on success, else FALSE with file.status denoting the error.
  180.  
  181.   Before closing, all changed data is written out using FlushBuf().
  182.  
  183.  
  184. PROCEDURE read * (VAR file: File; VAR to: ARRAY OF s.BYTE);
  185. PROCEDURE Read * (VAR file: File; VAR to: ARRAY OF s.BYTE): BOOLEAN;
  186.  
  187.   Read data from a file.
  188.  
  189.   Arguments:
  190.     file: the file to read.
  191.     to  : the buffer to read into.
  192.  
  193.   Result:
  194.     TRUE on success, else FALSE with file.status denoting the error.
  195.  
  196.   The function optimizes large reads by circumventing file's buffer then.
  197.  
  198.  
  199. PROCEDURE readBlock * ( VAR    file : File
  200.                       ;          to : s.ADDRESS
  201.                       ;         size: LONGINT
  202.                       ; VAR actSize : LONGINT
  203.                       );
  204. PROCEDURE ReadBlock * ( VAR    file : File
  205.                       ;          to : s.ADDRESS
  206.                       ;         size: LONGINT
  207.                       ; VAR actSize : LONGINT
  208.                       ): BOOLEAN;
  209.  
  210.   Read a block of data from a file.
  211.  
  212.   Arguments:
  213.     file   : the file to read.
  214.     to     : the address of the buffer to read into.
  215.     size   : the length of the buffer = number of bytes to read.
  216.     actSize: variable taking the actual number of bytes read.
  217.  
  218.   Result:
  219.     TRUE on success, else FALSE with file.status denoting the error.
  220.  
  221.   The function optimizes large reads by circumventing file's buffer then.
  222.  
  223.  
  224. PROCEDURE readChar * (VAR file: File; VAR ch: CHAR);
  225. PROCEDURE ReadChar * (VAR file: File; VAR ch: CHAR): BOOLEAN;
  226.  
  227.   Read a character from a file.
  228.  
  229.   Arguments:
  230.     file: the file to read.
  231.     ch  : the variable taking the character read.
  232.  
  233.   Result:
  234.     TRUE on success, else FALSE with file.status denoting the error.
  235.  
  236.   On eof, ch is set to EOF.
  237.  
  238.  
  239. PROCEDURE readString * (VAR file: File; VAR to: ARRAY OF CHAR);
  240. PROCEDURE ReadString * (VAR file: File; VAR to: ARRAY OF CHAR): BOOLEAN;
  241.  
  242.   Read a string from a file.
  243.  
  244.   Arguments:
  245.     file: the file to read.
  246.     to  : the buffer to read the string into.
  247.  
  248.   Result:
  249.     TRUE on success, else FALSE with file.status denoting the error.
  250.  
  251.   The string is read until a \0 or a \n shows up (which is not stored)
  252.   or the buffer is exhausted. If possible, the read string is terminated
  253.   with \0.
  254.  
  255.  
  256. PROCEDURE ReadLongString * (VAR file: File): BOOLEAN;
  257. PROCEDURE readLString    * (VAR file: File);
  258. PROCEDURE ReadLString    * (VAR file: File): BOOLEAN;
  259.  
  260.   Read a long string from a file.
  261.  
  262.   Arguments:
  263.     file: the file to read.
  264.  
  265.   Result:
  266.     TRUE on success, else FALSE with file.status denoting the error.
  267.     The read string is store in file.string.
  268.  
  269.   The string is read until a \0 or a \n shows up (which is not stored).
  270.   If possible, the read string is terminated with \0.
  271.  
  272.   ReadLongString() is a compatibility function to FileSystem.
  273.  
  274.  
  275. PROCEDURE write * (VAR file: File; VAR from: ARRAY OF s.BYTE);
  276. PROCEDURE Write * (VAR file: File; VAR from: ARRAY OF s.BYTE): BOOLEAN;
  277.  
  278.   Write data to a file.
  279.  
  280.   Arguments:
  281.     file: the file to write.
  282.     from: the buffer to write from.
  283.  
  284.   Result:
  285.     TRUE on success, else FALSE with file.status denoting the error.
  286.  
  287.   The function optimizes large writes by circumventing file's buffer then.
  288.  
  289.  
  290. PROCEDURE writeBlock * ( VAR    file : File
  291.                        ;        from : s.ADDRESS
  292.                        ;        size : LONGINT
  293.                        ; VAR actSize : LONGINT
  294.                        );
  295. PROCEDURE WriteBlock * ( VAR    file : File
  296.                        ;        from : s.ADDRESS
  297.                        ;        size : LONGINT
  298.                        ; VAR actSize : LONGINT
  299.                        ): BOOLEAN;
  300.  
  301.   Write a block of data to a file.
  302.  
  303.   Arguments:
  304.     file    : the file to write.
  305.     from    : the address of the buffer to write from.
  306.     size    : the length of the buffer = the number of bytes to write.
  307.     actSize : variable taking the actual number of bytes written.
  308.  
  309.   Result:
  310.     TRUE on success, else FALSE with file.status denoting the error.
  311.     actsize: the number of bytes written.
  312.  
  313.   The function optimizes large writes by circumventing file's buffer then.
  314.  
  315.  
  316. PROCEDURE writeChar * (VAR file: File; ch: CHAR);
  317. PROCEDURE WriteChar * (VAR file: File; ch: CHAR): BOOLEAN;
  318.  
  319.   Write a character to a file.
  320.  
  321.   Arguments:
  322.     file: the file to write.
  323.     ch  : the character to write.
  324.  
  325.   Result:
  326.     TRUE on success, else FALSE with file.status denoting the error.
  327.  
  328.  
  329. PROCEDURE writeString * (VAR file: File; from: ARRAY OF CHAR);
  330. PROCEDURE WriteString * (VAR file: File; from: ARRAY OF CHAR): BOOLEAN;
  331.  
  332.   Write a string to a file.
  333.  
  334.   Arguments:
  335.     file: the file to write.
  336.     from: the string to write.
  337.  
  338.   Result:
  339.     TRUE on success, else FALSE with file.status denoting the error.
  340.  
  341.   The function writes the string plus one \n character.
  342.  
  343.  
  344. PROCEDURE Size * (VAR file: File): LONGINT;
  345.  
  346.   Determine the size of a file.
  347.  
  348.   Arguments:
  349.     file: the file to query.
  350.  
  351.   Result:
  352.     The file's size in bytes.
  353.  
  354.  
  355. PROCEDURE Position * (VAR file: File): LONGINT;
  356.  
  357.   Determine the current position in a file.
  358.  
  359.   Arguments:
  360.     file: the file to query.
  361.  
  362.   Result:
  363.     The position within the file in bytes.
  364.  
  365.  
  366. PROCEDURE move * (VAR file: File; to: LONGINT);
  367. PROCEDURE Move * (VAR file: File; to: LONGINT): BOOLEAN;
  368.  
  369.   Seek within a file.
  370.  
  371.   Arguments:
  372.     file: the file to seek in.
  373.     to  : the new position to seek, counted in bytes from the files start.
  374.  
  375.   Result:
  376.     TRUE on success, else FALSE with file.status denoting the error.
  377.  
  378.  
  379. PROCEDURE forward * (VAR file: File; to: LONGINT);
  380. PROCEDURE Forward * (VAR file: File; to: LONGINT): BOOLEAN;
  381.  
  382.   Seek forward within a file.
  383.  
  384.   Arguments:
  385.     file: the file to seek in.
  386.     to  : the number of bytes to skip forward.
  387.  
  388.   Result:
  389.     TRUE on success, else FALSE with file.status denoting the error.
  390.  
  391.  
  392. PROCEDURE backward * (VAR file: File; to: LONGINT);
  393. PROCEDURE Backward * (VAR file: File; to: LONGINT): BOOLEAN;
  394.  
  395.   Seek backward within a file.
  396.  
  397.   Arguments:
  398.     file: the file to seek in.
  399.     to  : the number of bytes to skip backward.
  400.  
  401.   Result:
  402.     TRUE on success, else FALSE with file.status denoting the error.
  403.  
  404.  
  405. PROCEDURE delete * (VAR file: File);
  406. PROCEDURE Delete * (VAR file: File): BOOLEAN;
  407.  
  408.   Delete a file.
  409.  
  410.   Arguments:
  411.     file: the file to delete.
  412.  
  413.   Result:
  414.     TRUE on success, else FALSE with file.status denoting the error.
  415.  
  416.   The file is closed, then deleted.
  417.  
  418.  
  419. PROCEDURE Exists * (name: ARRAY OF CHAR): BOOLEAN;
  420.  
  421.   Check if a named file exists.
  422.  
  423.   Arguments:
  424.     name: the filename to check.
  425.  
  426.   Result:
  427.     TRUE if the file exists, else FALSE.
  428.  
  429.   BUGS:
  430.     Doesn't handle multi-assigns.
  431.  
  432. END FSystem.
  433.  
  434.